| Server IP : 121.121.20.254 / Your IP : 216.73.216.202 Web Server : Microsoft-IIS/10.0 System : Windows NT WEB-SERVER 10.0 build 20348 (Windows Server 2022) AMD64 User : IUSR ( 0) PHP Version : 8.3.28 Disable Function : NONE MySQL : ON | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : C:/Python315/Doc/html/c-api/ |
Upload File : |
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="Type Objects" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/c-api/type.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="Creating Heap-Allocated Types: The following function is used to create heap types: Heap types created without the Py_TPFLAGS_IMMUTABLETYPE flag may be modified, for example by setting attributes o..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="Creating Heap-Allocated Types: The following function is used to create heap types: Heap types created without the Py_TPFLAGS_IMMUTABLETYPE flag may be modified, for example by setting attributes o..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>Type Objects — Python 3.15.0rc1 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=4365c8fe" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=791e38b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0rc1 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="The None Object" href="none.html" />
<link rel="prev" title="Concrete Objects Layer" href="concrete.html" />
<link rel="canonical" href="https://docs.python.org/3/c-api/type.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Type Objects</a><ul>
<li><a class="reference internal" href="#creating-heap-allocated-types">Creating Heap-Allocated Types</a><ul>
<li><a class="reference internal" href="#type-slot-ids">Type slot IDs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#soft-deprecated-api">Soft-deprecated API</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="concrete.html"
title="previous chapter">Concrete Objects Layer</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="none.html"
title="next chapter">The <code class="docutils literal notranslate"><span class="pre">None</span></code> Object</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "c-api/type.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/c-api/type.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="none.html" title="The None Object"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="concrete.html" title="Concrete Objects Layer"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0rc1 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API reference manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
<li class="nav-item nav-item-this"><a href="">Type Objects</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="type-objects">
<span id="typeobjects"></span><h1>Type Objects<a class="headerlink" href="#type-objects" title="Link to this heading">¶</a></h1>
<dl class="c type" id="index-0">
<dt class="sig sig-object c" id="c.PyTypeObject">
<span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyTypeObject</span></span></span><a class="headerlink" href="#c.PyTypeObject" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> (as an opaque struct).</em><p>The C structure of the objects used to describe built-in types.</p>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.PyType_Type">
<a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_Type</span></span></span><a class="headerlink" href="#c.PyType_Type" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is the type object for type objects; it is the same object as
<a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type</span></code></a> in the Python layer.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_Check">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_Check</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_Check" title="Link to this definition">¶</a><br /></dt>
<dd><p>Return non-zero if the object <em>o</em> is a type object, including instances of
types derived from the standard type object. Return 0 in all other cases.
This function always succeeds.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_CheckExact">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_CheckExact</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_CheckExact" title="Link to this definition">¶</a><br /></dt>
<dd><p>Return non-zero if the object <em>o</em> is a type object, but not a subtype of
the standard type object. Return 0 in all other cases. This function
always succeeds.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_ClearCache">
<span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_ClearCache</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_ClearCache" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Clear the internal lookup cache. Return the current version tag.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetFlags">
<span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">long</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetFlags</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetFlags" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_flags" title="PyTypeObject.tp_flags"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_flags</span></code></a> member of <em>type</em>. This function is primarily
meant for use with <code class="docutils literal notranslate"><span class="pre">Py_LIMITED_API</span></code>; the individual flag bits are
guaranteed to be stable across Python releases, but access to
<code class="xref c c-member docutils literal notranslate"><span class="pre">tp_flags</span></code> itself is not part of the <a class="reference internal" href="stable.html#limited-c-api"><span class="std std-ref">limited API</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.2.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.4: </span>The return type is now <code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> rather than <code class="docutils literal notranslate"><span class="pre">long</span></code>.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetDict">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetDict</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetDict" title="Link to this definition">¶</a><br /></dt>
<dd><p>Return the type object’s internal namespace, which is otherwise only
exposed via a read-only proxy (<a class="reference internal" href="../reference/datamodel.html#type.__dict__" title="type.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">cls.__dict__</span></code></a>).
This is a
replacement for accessing <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_dict" title="PyTypeObject.tp_dict"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dict</span></code></a> directly.
The returned dictionary must be treated as read-only.</p>
<p>This function is meant for specific embedding and language-binding cases,
where direct access to the dict is necessary and indirect access
(e.g. via the proxy or <a class="reference internal" href="object.html#c.PyObject_GetAttr" title="PyObject_GetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetAttr()</span></code></a>) isn’t adequate.</p>
<p>Extension modules should continue to use <code class="docutils literal notranslate"><span class="pre">tp_dict</span></code>,
directly or indirectly, when setting up their own types.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.12.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_Modified">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_Modified</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_Modified" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Invalidate the internal lookup cache for the type and all of its
subtypes. This function must be called after any manual
modification of the attributes or base classes of the type.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_AddWatcher">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_AddWatcher</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyType_WatchCallback" title="PyType_WatchCallback"><span class="n"><span class="pre">PyType_WatchCallback</span></span></a><span class="w"> </span><span class="n"><span class="pre">callback</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_AddWatcher" title="Link to this definition">¶</a><br /></dt>
<dd><p>Register <em>callback</em> as a type watcher. Return a non-negative integer ID
which must be passed to future calls to <a class="reference internal" href="#c.PyType_Watch" title="PyType_Watch"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Watch()</span></code></a>. In case of
error (e.g. no more watcher IDs available), return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and set an
exception.</p>
<p>In free-threaded builds, <a class="reference internal" href="#c.PyType_AddWatcher" title="PyType_AddWatcher"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_AddWatcher()</span></code></a> is not thread-safe,
so it must be called at start up (before spawning the first thread).</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.12.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_ClearWatcher">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_ClearWatcher</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">watcher_id</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_ClearWatcher" title="Link to this definition">¶</a><br /></dt>
<dd><p>Clear watcher identified by <em>watcher_id</em> (previously returned from
<a class="reference internal" href="#c.PyType_AddWatcher" title="PyType_AddWatcher"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_AddWatcher()</span></code></a>). Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error (e.g.
if <em>watcher_id</em> was never registered.)</p>
<p>An extension should never call <code class="docutils literal notranslate"><span class="pre">PyType_ClearWatcher</span></code> with a <em>watcher_id</em>
that was not returned to it by a previous call to
<a class="reference internal" href="#c.PyType_AddWatcher" title="PyType_AddWatcher"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_AddWatcher()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.12.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_Watch">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_Watch</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">watcher_id</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_Watch" title="Link to this definition">¶</a><br /></dt>
<dd><p>Mark <em>type</em> as watched. The callback granted <em>watcher_id</em> by
<a class="reference internal" href="#c.PyType_AddWatcher" title="PyType_AddWatcher"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_AddWatcher()</span></code></a> will be called whenever
<a class="reference internal" href="#c.PyType_Modified" title="PyType_Modified"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Modified()</span></code></a> reports a change to <em>type</em>. (The callback may be
called only once for a series of consecutive modifications to <em>type</em>, if
<code class="xref c c-func docutils literal notranslate"><span class="pre">_PyType_Lookup()</span></code> is not called on <em>type</em> between the modifications;
this is an implementation detail and subject to change.)</p>
<p>The callback is also invoked when a watched heap type is deallocated.</p>
<p>An extension should never call <code class="docutils literal notranslate"><span class="pre">PyType_Watch</span></code> with a <em>watcher_id</em> that was
not returned to it by a previous call to <a class="reference internal" href="#c.PyType_AddWatcher" title="PyType_AddWatcher"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_AddWatcher()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.12.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>The callback is now also invoked when a watched heap type is deallocated.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_Unwatch">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_Unwatch</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">watcher_id</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_Unwatch" title="Link to this definition">¶</a><br /></dt>
<dd><p>Mark <em>type</em> as not watched. This undoes a previous call to
<a class="reference internal" href="#c.PyType_Watch" title="PyType_Watch"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Watch()</span></code></a>. <em>type</em> must not be <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<p>An extension should never call this function with a <em>watcher_id</em> that was
not returned to it by a previous call to <a class="reference internal" href="#c.PyType_AddWatcher" title="PyType_AddWatcher"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_AddWatcher()</span></code></a>.</p>
<p>On success, this function returns <code class="docutils literal notranslate"><span class="pre">0</span></code>. On failure, this function returns
<code class="docutils literal notranslate"><span class="pre">-1</span></code> with an exception set.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.12.</span></p>
</div>
</dd></dl>
<dl class="c type">
<dt class="sig sig-object c" id="c.PyType_WatchCallback">
<span class="k"><span class="pre">typedef</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="p"><span class="pre">(</span></span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_WatchCallback</span></span></span><span class="p"><span class="pre">)</span></span><span class="p"><span class="pre">(</span></span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="p"><span class="pre">)</span></span><a class="headerlink" href="#c.PyType_WatchCallback" title="Link to this definition">¶</a><br /></dt>
<dd><p>Type of a type-watcher callback function.</p>
<p>The callback must not modify <em>type</em> or cause <a class="reference internal" href="#c.PyType_Modified" title="PyType_Modified"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Modified()</span></code></a> to be
called on <em>type</em> or any type in its MRO; violating this rule could cause
infinite recursion.</p>
<p>The callback may be called during type deallocation. In this case, the type
object is temporarily resurrected (its reference count is at least 1) and all
its attributes are still valid. However, the callback should not store new
strong references to the type, as this would resurrect the object and prevent
its deallocation.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.12.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>The callback may now be called during deallocation of a watched heap type.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_HasFeature">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_HasFeature</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">feature</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_HasFeature" title="Link to this definition">¶</a><br /></dt>
<dd><p>Return non-zero if the type object <em>o</em> sets the feature <em>feature</em>.
Type features are denoted by single bit flags.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_FastSubclass">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_FastSubclass</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">flag</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_FastSubclass" title="Link to this definition">¶</a><br /></dt>
<dd><p>Return non-zero if the type object <em>type</em> sets the subclass flag <em>flag</em>.
Subclass flags are denoted by
<a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_LONG_SUBCLASS" title="Py_TPFLAGS_LONG_SUBCLASS"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_*_SUBCLASS</span></code></a>.
This function is used by many <code class="docutils literal notranslate"><span class="pre">_Check</span></code> functions for common types.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="object.html#c.PyObject_TypeCheck" title="PyObject_TypeCheck"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_TypeCheck()</span></code></a>, which is used as a slower alternative in
<code class="docutils literal notranslate"><span class="pre">_Check</span></code> functions for types that don’t come with subclass flags.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_IS_GC">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_IS_GC</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_IS_GC" title="Link to this definition">¶</a><br /></dt>
<dd><p>Return true if the type object includes support for the cycle detector; this
tests the type flag <a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_IsSubtype">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_IsSubtype</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">a</span></span>, <a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">b</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_IsSubtype" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return true if <em>a</em> is a subtype of <em>b</em>.</p>
<p>This function only checks for actual subtypes, which means that
<a class="reference internal" href="../reference/datamodel.html#type.__subclasscheck__" title="type.__subclasscheck__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__subclasscheck__()</span></code></a> is not called on <em>b</em>. Call
<a class="reference internal" href="object.html#c.PyObject_IsSubclass" title="PyObject_IsSubclass"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_IsSubclass()</span></code></a> to do the same check that <a class="reference internal" href="../library/functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">issubclass()</span></code></a>
would do.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GenericAlloc">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GenericAlloc</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">nitems</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GenericAlloc" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Generic handler for the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_alloc" title="PyTypeObject.tp_alloc"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_alloc</span></code></a> slot of a type
object. Uses Python’s default memory allocation mechanism to allocate memory
for a new instance, zeros the memory, then initializes the memory as if by
calling <a class="reference internal" href="allocation.html#c.PyObject_Init" title="PyObject_Init"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Init()</span></code></a> or <a class="reference internal" href="allocation.html#c.PyObject_InitVar" title="PyObject_InitVar"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_InitVar()</span></code></a>.</p>
<p>Do not call this directly to allocate memory for an object; call the type’s
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_alloc" title="PyTypeObject.tp_alloc"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_alloc</span></code></a> slot instead.</p>
<p>For types that support garbage collection (i.e., the
<a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> flag is set), this function behaves like
<a class="reference internal" href="gcsupport.html#c.PyObject_GC_New" title="PyObject_GC_New"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyObject_GC_New</span></code></a> or <a class="reference internal" href="gcsupport.html#c.PyObject_GC_NewVar" title="PyObject_GC_NewVar"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyObject_GC_NewVar</span></code></a> (except the
memory is guaranteed to be zeroed before initialization), and should be
paired with <a class="reference internal" href="gcsupport.html#c.PyObject_GC_Del" title="PyObject_GC_Del"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_Del()</span></code></a> in <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_free" title="PyTypeObject.tp_free"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_free</span></code></a>.
Otherwise, it behaves like <a class="reference internal" href="allocation.html#c.PyObject_New" title="PyObject_New"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyObject_New</span></code></a> or
<a class="reference internal" href="allocation.html#c.PyObject_NewVar" title="PyObject_NewVar"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyObject_NewVar</span></code></a> (except the memory is guaranteed to be zeroed
before initialization) and should be paired with <a class="reference internal" href="memory.html#c.PyObject_Free" title="PyObject_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Free()</span></code></a> in
<code class="xref c c-member docutils literal notranslate"><span class="pre">tp_free</span></code>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GenericNew">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GenericNew</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">kwds</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GenericNew" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Generic handler for the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> slot of a type
object. Creates a new instance using the type’s
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_alloc" title="PyTypeObject.tp_alloc"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_alloc</span></code></a> slot and returns the resulting object.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_Ready">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_Ready</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_Ready" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Finalize a type object. This should be called on all type objects to finish
their initialization. This function is responsible for adding inherited slots
from a type’s base class. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, or return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and sets an
exception on error.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If some of the base classes implements the GC protocol and the provided
type does not include the <a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> in its flags, then
the GC protocol will be automatically implemented from its parents. On
the contrary, if the type being created does include
<code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code> in its flags then it <strong>must</strong> implement the
GC protocol itself by at least implementing the
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> handle.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetName">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetName</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetName" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.11.</em><p>Return the type’s name. Equivalent to getting the type’s
<a class="reference internal" href="../reference/datamodel.html#type.__name__" title="type.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code></a> attribute.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.11.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetQualName">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetQualName</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetQualName" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.11.</em><p>Return the type’s qualified name. Equivalent to getting the
type’s <a class="reference internal" href="../reference/datamodel.html#type.__qualname__" title="type.__qualname__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__qualname__</span></code></a> attribute.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.11.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetFullyQualifiedName">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetFullyQualifiedName</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetFullyQualifiedName" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.13.</em><p>Return the type’s fully qualified name. Equivalent to
<code class="docutils literal notranslate"><span class="pre">f"{type.__module__}.{type.__qualname__}"</span></code>, or <a class="reference internal" href="../reference/datamodel.html#type.__qualname__" title="type.__qualname__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type.__qualname__</span></code></a>
if <a class="reference internal" href="../reference/datamodel.html#type.__module__" title="type.__module__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type.__module__</span></code></a> is not a string or is equal to <code class="docutils literal notranslate"><span class="pre">"builtins"</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.13.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetModuleName">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetModuleName</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetModuleName" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.13.</em><p>Return the type’s module name. Equivalent to getting the
<a class="reference internal" href="../reference/datamodel.html#type.__module__" title="type.__module__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type.__module__</span></code></a> attribute.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.13.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetSlot">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetSlot</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">slot</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetSlot" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.4.</em><p>Return the function pointer stored in the given slot. If the
result is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, this indicates that either the slot is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>,
or that the function was called with invalid parameters.
Callers will typically cast the result pointer into the appropriate
function type.</p>
<p>See <a class="reference internal" href="#c.PyType_Slot.slot" title="PyType_Slot.slot"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Slot.slot</span></code></a> for possible values of the <em>slot</em> argument.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.10: </span><a class="reference internal" href="#c.PyType_GetSlot" title="PyType_GetSlot"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetSlot()</span></code></a> can now accept all types.
Previously, it was limited to <a class="reference internal" href="typeobj.html#heap-types"><span class="std std-ref">heap types</span></a>.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetModule">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetModule</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetModule" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_borrowed_ref">Return value: Borrowed reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>Return the module object associated with the given type when the type was
created using <a class="reference internal" href="#c.PyType_FromModuleAndSpec" title="PyType_FromModuleAndSpec"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromModuleAndSpec()</span></code></a>.</p>
<p>The returned reference is <a class="reference internal" href="../glossary.html#term-borrowed-reference"><span class="xref std std-term">borrowed</span></a> from <em>type</em>,
and will be valid as long as you hold a reference to <em>type</em>.
Do not release it with <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> or similar.</p>
<p>If no module is associated with the given type, sets <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-class docutils literal notranslate"><span class="pre">TypeError</span></code></a>
and returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<p>This function is usually used to get the module in which a method is defined.
Note that in such a method, <code class="docutils literal notranslate"><span class="pre">PyType_GetModule(Py_TYPE(self))</span></code>
may not return the intended result.
<code class="docutils literal notranslate"><span class="pre">Py_TYPE(self)</span></code> may be a <em>subclass</em> of the intended class, and subclasses
are not necessarily defined in the same module as their superclass.
See <a class="reference internal" href="structures.html#c.PyCMethod" title="PyCMethod"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCMethod</span></code></a> to get the class that defines the method.
See <a class="reference internal" href="#c.PyType_GetModuleByToken" title="PyType_GetModuleByToken"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetModuleByToken()</span></code></a> for cases when <code class="xref c c-type docutils literal notranslate"><span class="pre">PyCMethod</span></code>
cannot be used.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.9.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetModuleState">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetModuleState</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetModuleState" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>Return the state of the module object associated with the given type.
This is a shortcut for calling <a class="reference internal" href="module.html#c.PyModule_GetState" title="PyModule_GetState"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_GetState()</span></code></a> on the result
of <a class="reference internal" href="#c.PyType_GetModule" title="PyType_GetModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetModule()</span></code></a>.</p>
<p>If no module is associated with the given type, sets <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-class docutils literal notranslate"><span class="pre">TypeError</span></code></a>
and returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<p>If the <em>type</em> has an associated module but its state is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>,
returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code> without setting an exception.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.9.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetModuleByToken">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetModuleByToken</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">mod_token</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetModuleByToken" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Find the first superclass whose module has the given
<a class="reference internal" href="module.html#ext-module-token"><span class="std std-ref">module token</span></a>, and return that module.</p>
<p>If no module is found, raises a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-class docutils literal notranslate"><span class="pre">TypeError</span></code></a> and returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<p>This function is intended to be used together with
<a class="reference internal" href="module.html#c.PyModule_GetState" title="PyModule_GetState"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_GetState()</span></code></a> to get module state from slot methods (such as
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_init</span></code></a> or <a class="reference internal" href="typeobj.html#c.PyNumberMethods.nb_add" title="PyNumberMethods.nb_add"><code class="xref c c-member docutils literal notranslate"><span class="pre">nb_add</span></code></a>)
and other places where a method’s defining class cannot be passed using the
<a class="reference internal" href="structures.html#c.PyCMethod" title="PyCMethod"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCMethod</span></code></a> calling convention.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetModuleByDef">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetModuleByDef</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span>, <span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="module.html#c.PyModuleDef" title="PyModuleDef"><span class="n"><span class="pre">PyModuleDef</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">def</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetModuleByDef" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_borrowed_ref">Return value: Borrowed reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.13.</em><p>Find the first superclass whose module was created from the given
<a class="reference internal" href="module.html#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code></a> <em>def</em>, or whose <a class="reference internal" href="module.html#ext-module-token"><span class="std std-ref">module token</span></a>
is equal to <em>def</em>, and return that module.</p>
<p>Note that modules created from a <a class="reference internal" href="module.html#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code></a> always have their
token set to the <code class="xref c c-type docutils literal notranslate"><span class="pre">PyModuleDef</span></code>’s address.
In other words, this function is equivalent to
<a class="reference internal" href="#c.PyType_GetModuleByToken" title="PyType_GetModuleByToken"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetModuleByToken()</span></code></a>, except that it:</p>
<ul class="simple">
<li><p>returns a borrowed reference, and</p></li>
<li><p>has a non-<code class="docutils literal notranslate"><span class="pre">void*</span></code> argument type (which is a cosmetic difference in C).</p></li>
</ul>
<p>The returned reference is <a class="reference internal" href="../glossary.html#term-borrowed-reference"><span class="xref std std-term">borrowed</span></a> from <em>type</em>,
and will be valid as long as you hold a reference to <em>type</em>.
Do not release it with <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> or similar.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.11.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_GetBaseByToken">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetBaseByToken</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">tp_token</span></span>, <a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">result</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetBaseByToken" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.14.</em><p>Find the first superclass in <em>type</em>’s <a class="reference internal" href="../glossary.html#term-method-resolution-order"><span class="xref std std-term">method resolution order</span></a> whose
<a class="reference internal" href="#c.Py_tp_token" title="Py_tp_token"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_token</span></code></a> token is equal to <em>tp_token</em>.</p>
<ul class="simple">
<li><p>If found, set <em>*result</em> to a new <a class="reference internal" href="../glossary.html#term-strong-reference"><span class="xref std std-term">strong reference</span></a>
to it and return <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p></li>
<li><p>If not found, set <em>*result</em> to <code class="docutils literal notranslate"><span class="pre">NULL</span></code> and return <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p></li>
<li><p>On error, set <em>*result</em> to <code class="docutils literal notranslate"><span class="pre">NULL</span></code> and return <code class="docutils literal notranslate"><span class="pre">-1</span></code> with an
exception set.</p></li>
</ul>
<p>The <em>result</em> argument may be <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, in which case <em>*result</em> is not set.
Use this if you need only the return value.</p>
<p>The <em>tp_token</em> argument may not be <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.14.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyUnstable_Type_AssignVersionTag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnstable_Type_AssignVersionTag</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnstable_Type_AssignVersionTag" title="Link to this definition">¶</a><br /></dt>
<dd><div class="unstable-c-api warning admonition">
<em>This is <a class="reference internal" href="stable.html#unstable-c-api"><span class="std std-ref">Unstable API</span></a>. It may change without warning in minor releases.</em></div>
<p>Attempt to assign a version tag to the given type.</p>
<p>Returns 1 if the type already had a valid version tag or a new one was
assigned, or 0 if a new tag could not be assigned.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.12.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_SUPPORTS_WEAKREFS">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_SUPPORTS_WEAKREFS</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_SUPPORTS_WEAKREFS" title="Link to this definition">¶</a><br /></dt>
<dd><p>Return true if instances of <em>type</em> support creating weak references, false
otherwise. This function always succeeds. <em>type</em> must not be <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<ul class="simple">
<li><p><a class="reference internal" href="weakref.html#weakrefobjects"><span class="std std-ref">Weak Reference Objects</span></a></p></li>
<li><p><a class="reference internal" href="../library/weakref.html#module-weakref" title="weakref: Support for weak references and weak dictionaries."><code class="xref py py-mod docutils literal notranslate"><span class="pre">weakref</span></code></a></p></li>
</ul>
</div>
</dd></dl>
<section id="creating-heap-allocated-types">
<span id="creating-heap-types"></span><h2>Creating Heap-Allocated Types<a class="headerlink" href="#creating-heap-allocated-types" title="Link to this heading">¶</a></h2>
<p>The following function is used to create <a class="reference internal" href="typeobj.html#heap-types"><span class="std std-ref">heap types</span></a>:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_FromSlots">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_FromSlots</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><a class="reference internal" href="slots.html#c.PySlot" title="PySlot"><span class="n"><span class="pre">PySlot</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">slots</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_FromSlots" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Create and return a <a class="reference internal" href="typeobj.html#heap-types"><span class="std std-ref">heap type</span></a> from a <code class="xref c c-type docutils literal notranslate"><span class="pre">PySlot</span></code>
array.
See <a class="reference internal" href="slots.html#capi-slots"><span class="std std-ref">Definition slots</span></a> for general information on slots,
and <a class="reference internal" href="#pyslot-type-slot-ids"><span class="std std-ref">Type slot IDs</span></a> for slots specific to type creation.</p>
<p>This function calls <a class="reference internal" href="#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready()</span></code></a> on the new type.</p>
<p>Note that this function does <em>not</em> fully match the behavior of
calling <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type()</span></code></a> or using the <a class="reference internal" href="../reference/compound_stmts.html#class"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">class</span></code></a> statement.
With user-provided base types or metaclasses, prefer
<a class="reference internal" href="call.html#capi-call"><span class="std std-ref">calling</span></a> <code class="xref py py-class docutils literal notranslate"><span class="pre">type</span></code> (or the metaclass)
over <code class="docutils literal notranslate"><span class="pre">PyType_From*</span></code> functions.
Specifically:</p>
<ul class="simple">
<li><p><a class="reference internal" href="../reference/datamodel.html#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a> is not called on the new class
(and it must be set to <code class="docutils literal notranslate"><span class="pre">type.__new__</span></code>).</p></li>
<li><p><a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> is not called on the new class.</p></li>
<li><p><a class="reference internal" href="../reference/datamodel.html#object.__init_subclass__" title="object.__init_subclass__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init_subclass__()</span></code></a> is not called on any bases.</p></li>
<li><p><a class="reference internal" href="../reference/datamodel.html#object.__set_name__" title="object.__set_name__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__set_name__()</span></code></a> is not called on new descriptors.</p></li>
</ul>
<p>Slots are typically defined as a global static constant arrays.
However, sometimes slot values are not statically known at compile time.
For example, slots like <a class="reference internal" href="#c.Py_tp_bases" title="Py_tp_bases"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_bases</span></code></a>, <a class="reference internal" href="#c.Py_tp_metaclass" title="Py_tp_metaclass"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_metaclass</span></code></a>
and <a class="reference internal" href="#c.Py_tp_module" title="Py_tp_module"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_module</span></code></a> require live Python objects.
In this case, it is recommended to put such slots on the stack,
and use <a class="reference internal" href="slots.html#c.Py_slot_subslots" title="Py_slot_subslots"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_slot_subslots</span></code></a> to refer to an array of static slots.
For example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n">PySlot</span><span class="w"> </span><span class="n">my_slots</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">PySlot_STATIC_DATA</span><span class="p">(</span><span class="n">Py_tp_name</span><span class="p">,</span><span class="w"> </span><span class="s">"MyClass"</span><span class="p">),</span>
<span class="w"> </span><span class="n">PySlot_FUNC</span><span class="p">(</span><span class="n">Py_tp_repr</span><span class="p">,</span><span class="w"> </span><span class="n">my_repr_func</span><span class="p">),</span>
<span class="w"> </span><span class="p">...</span>
<span class="w"> </span><span class="n">PySlot_END</span>
<span class="p">};</span>
<span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="nf">make_my_class</span><span class="p">(</span><span class="n">PyObject</span><span class="w"> </span><span class="o">*</span><span class="n">module</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">PySlot</span><span class="w"> </span><span class="n">all_slots</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">PySlot_STATIC_DATA</span><span class="p">(</span><span class="n">Py_slot_subslots</span><span class="p">,</span><span class="w"> </span><span class="n">my_slots</span><span class="p">),</span>
<span class="w"> </span><span class="n">PySlot_DATA</span><span class="p">(</span><span class="n">Py_tp_module</span><span class="p">,</span><span class="w"> </span><span class="n">module</span><span class="p">),</span>
<span class="w"> </span><span class="n">PySlot_END</span>
<span class="w"> </span><span class="p">};</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">PyType_FromSlots</span><span class="p">(</span><span class="n">all_slots</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
</dd></dl>
<p>Heap types created without the <a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_IMMUTABLETYPE" title="Py_TPFLAGS_IMMUTABLETYPE"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_IMMUTABLETYPE</span></code></a> flag may be
modified, for example by setting attributes on them, as with classes defined
in Python code.
Sometimes, such modifications are necessary to fully initialize a type,
but you may wish to prevent users from changing the type after
the initialization is done:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_Freeze">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_Freeze</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_Freeze" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.14.</em><p>Make a type immutable: set the <a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_IMMUTABLETYPE" title="Py_TPFLAGS_IMMUTABLETYPE"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_IMMUTABLETYPE</span></code></a> flag.</p>
<p>All base classes of <em>type</em> must be immutable.</p>
<p>On success, return <code class="docutils literal notranslate"><span class="pre">0</span></code>.
On error, set an exception and return <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>
<p>The type must not be used before it’s made immutable. For example, type
instances must not be created before the type is made immutable.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.14.</span></p>
</div>
</dd></dl>
<section id="type-slot-ids">
<span id="pyslot-type-slot-ids"></span><h3>Type slot IDs<a class="headerlink" href="#type-slot-ids" title="Link to this heading">¶</a></h3>
<p>Most type slot IDs are named like the field names of the structures
<a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a>, <a class="reference internal" href="typeobj.html#c.PyNumberMethods" title="PyNumberMethods"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyNumberMethods</span></code></a>,
<a class="reference internal" href="typeobj.html#c.PySequenceMethods" title="PySequenceMethods"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySequenceMethods</span></code></a>, <a class="reference internal" href="typeobj.html#c.PyMappingMethods" title="PyMappingMethods"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyMappingMethods</span></code></a> and
<a class="reference internal" href="typeobj.html#c.PyAsyncMethods" title="PyAsyncMethods"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyAsyncMethods</span></code></a> with an added <code class="docutils literal notranslate"><span class="pre">Py_</span></code> prefix.
For example, use:</p>
<ul class="simple">
<li><p><a class="reference internal" href="typeobj.html#c.Py_tp_dealloc" title="Py_tp_dealloc"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_dealloc</span></code></a> to set <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_dealloc" title="PyTypeObject.tp_dealloc"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyTypeObject.tp_dealloc</span></code></a></p></li>
<li><p><a class="reference internal" href="typeobj.html#c.Py_nb_add" title="Py_nb_add"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_nb_add</span></code></a> to set <a class="reference internal" href="typeobj.html#c.PyNumberMethods.nb_add" title="PyNumberMethods.nb_add"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyNumberMethods.nb_add</span></code></a></p></li>
<li><p><a class="reference internal" href="typeobj.html#c.Py_sq_length" title="Py_sq_length"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_sq_length</span></code></a> to set <a class="reference internal" href="typeobj.html#c.PySequenceMethods.sq_length" title="PySequenceMethods.sq_length"><code class="xref c c-member docutils literal notranslate"><span class="pre">PySequenceMethods.sq_length</span></code></a></p></li>
</ul>
<p>The following slots need additional considerations when specified as slots:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#c.Py_tp_name" title="Py_tp_name"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_name</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_tp_basicsize" title="Py_tp_basicsize"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_basicsize</span></code></a> and <a class="reference internal" href="#c.Py_tp_extra_basicsize" title="Py_tp_extra_basicsize"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_extra_basicsize</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_tp_itemsize" title="Py_tp_itemsize"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_itemsize</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_tp_flags" title="Py_tp_flags"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_flags</span></code></a></p></li>
</ul>
<p>Additional slots do not directly correspond to a <code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code>
struct field:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#c.Py_tp_token" title="Py_tp_token"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_token</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_tp_metaclass" title="Py_tp_metaclass"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_metaclass</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_tp_module" title="Py_tp_module"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_module</span></code></a></p></li>
</ul>
<p>The following “offset” fields cannot be set using <a class="reference internal" href="#c.PyType_Slot" title="PyType_Slot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyType_Slot</span></code></a>:</p>
<ul class="simple">
<li><p><a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_weaklistoffset" title="PyTypeObject.tp_weaklistoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_weaklistoffset</span></code></a>
(use <a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_MANAGED_WEAKREF" title="Py_TPFLAGS_MANAGED_WEAKREF"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_MANAGED_WEAKREF</span></code></a> instead if possible)</p></li>
<li><p><a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dictoffset</span></code></a>
(use <a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_MANAGED_DICT" title="Py_TPFLAGS_MANAGED_DICT"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_MANAGED_DICT</span></code></a> instead if possible)</p></li>
<li><p><a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_vectorcall_offset" title="PyTypeObject.tp_vectorcall_offset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_vectorcall_offset</span></code></a>
(use <code class="docutils literal notranslate"><span class="pre">"__vectorcalloffset__"</span></code> in <a class="reference internal" href="structures.html#pymemberdef-offsets"><span class="std std-ref">PyMemberDef</span></a>)</p></li>
</ul>
<p>If it is not possible to switch to a <code class="docutils literal notranslate"><span class="pre">MANAGED</span></code> flag (for example,
for vectorcall or to support Python older than 3.12), specify the
offset in <a class="reference internal" href="typeobj.html#c.Py_tp_members" title="Py_tp_members"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_members</span></code></a>.
See <a class="reference internal" href="structures.html#pymemberdef-offsets"><span class="std std-ref">PyMemberDef documentation</span></a>
for details.</p>
<p>The following internal fields cannot be set at all when creating a heap
type:</p>
<ul class="simple">
<li><p><a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_dict" title="PyTypeObject.tp_dict"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dict</span></code></a>,
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_mro" title="PyTypeObject.tp_mro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_mro</span></code></a>,
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_cache" title="PyTypeObject.tp_cache"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_cache</span></code></a>,
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_subclasses" title="PyTypeObject.tp_subclasses"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_subclasses</span></code></a>, and
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_weaklist" title="PyTypeObject.tp_weaklist"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_weaklist</span></code></a>.</p></li>
</ul>
<p>The <a class="reference internal" href="#c.Py_tp_base" title="Py_tp_base"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_base</span></code></a> slot is equivalent to <a class="reference internal" href="#c.Py_tp_bases" title="Py_tp_bases"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_bases</span></code></a>;
both may be set either to a type or a tuple of types.
If both are specified, the value of <code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_bases</span></code>
is used.</p>
<p>Slot values may not be <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, except for the following:</p>
<ul class="simple">
<li><p><a class="reference internal" href="typeobj.html#c.Py_tp_doc" title="Py_tp_doc"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_doc</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_tp_token" title="Py_tp_token"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_token</span></code></a> (for clarity, prefer <a class="reference internal" href="#c.Py_TP_USE_SPEC" title="Py_TP_USE_SPEC"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_TP_USE_SPEC</span></code></a>
rather than <code class="docutils literal notranslate"><span class="pre">NULL</span></code>)</p></li>
</ul>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.9: </span>Slots in <a class="reference internal" href="typeobj.html#c.PyBufferProcs" title="PyBufferProcs"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyBufferProcs</span></code></a> may be set in the unlimited API.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.11: </span><a class="reference internal" href="typeobj.html#c.PyBufferProcs.bf_getbuffer" title="PyBufferProcs.bf_getbuffer"><code class="xref c c-member docutils literal notranslate"><span class="pre">bf_getbuffer</span></code></a> and
<a class="reference internal" href="typeobj.html#c.PyBufferProcs.bf_releasebuffer" title="PyBufferProcs.bf_releasebuffer"><code class="xref c c-member docutils literal notranslate"><span class="pre">bf_releasebuffer</span></code></a> are now available
under the <a class="reference internal" href="stable.html#limited-c-api"><span class="std std-ref">limited API</span></a>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.14: </span>The field <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_vectorcall" title="PyTypeObject.tp_vectorcall"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_vectorcall</span></code></a> can now be set
using <a class="reference internal" href="typeobj.html#c.Py_tp_vectorcall" title="Py_tp_vectorcall"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_vectorcall</span></code></a>. See the field’s documentation
for details.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>The <a class="reference internal" href="#c.Py_tp_bases" title="Py_tp_bases"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_bases</span></code></a> slot may be set to a single type object,
making it equivalent to the <a class="reference internal" href="#c.Py_tp_base" title="Py_tp_base"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_base</span></code></a> slot.
Previously, a tuple of types was required.</p>
</div>
<p>The following slots correspond to fields in the underlying type structure,
but need extra remarks for use as slots:</p>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_tp_name">
<span class="sig-name descname"><span class="n"><span class="pre">Py_tp_name</span></span></span><a class="headerlink" href="#c.Py_tp_name" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for the name of the type,
used to set <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_name" title="PyTypeObject.tp_name"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyTypeObject.tp_name</span></code></a>.</p>
<p>This slot (or <a class="reference internal" href="#c.PyType_Spec.name" title="PyType_Spec.name"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.name</span></code></a>) is required to create a type.</p>
<p>This may not be used in <a class="reference internal" href="#c.PyType_Spec.slots" title="PyType_Spec.slots"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.slots</span></code></a>.
Use <a class="reference internal" href="#c.PyType_Spec.name" title="PyType_Spec.name"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.name</span></code></a> instead.</p>
<div class="impl-detail compound">
<p><strong>CPython implementation detail:</strong> CPython processes slots in order.
It is recommended to put <code class="docutils literal notranslate"><span class="pre">Py_tp_name</span></code> at the beginning of the slots
array, so that if processing of a later slots fails, error messages
can include the name.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_tp_basicsize">
<span class="sig-name descname"><span class="n"><span class="pre">Py_tp_basicsize</span></span></span><a class="headerlink" href="#c.Py_tp_basicsize" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for the size of the instance in bytes.
It is used to set <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyTypeObject.tp_basicsize</span></code></a>.</p>
<p>The value must be positive.</p>
<p>This may not be used in <a class="reference internal" href="#c.PyType_Spec.slots" title="PyType_Spec.slots"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.slots</span></code></a>.
Use <a class="reference internal" href="#c.PyType_Spec.basicsize" title="PyType_Spec.basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.basicsize</span></code></a> instead.</p>
<p>This slot may not be used with <a class="reference internal" href="#c.PyType_GetSlot" title="PyType_GetSlot"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetSlot()</span></code></a>.
Use <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyTypeObject.tp_basicsize</span></code></a> instead if needed, but be aware
that a type’s size is often considered an implementation detail.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_tp_extra_basicsize">
<span class="sig-name descname"><span class="n"><span class="pre">Py_tp_extra_basicsize</span></span></span><a class="headerlink" href="#c.Py_tp_extra_basicsize" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for type data size in bytes, that is,
how much space instances of the class need <em>in addition</em>
to space needed for superclasses.</p>
<p>The value is used, together with the size of superclasses, to set
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyTypeObject.tp_basicsize</span></code></a>.
Python will insert padding as needed to meet
<code class="xref c c-member docutils literal notranslate"><span class="pre">tp_basicsize</span></code>’s alignment requirements.</p>
<p>Use <a class="reference internal" href="object.html#c.PyObject_GetTypeData" title="PyObject_GetTypeData"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetTypeData()</span></code></a> to get a pointer to subclass-specific
memory reserved this way.</p>
<p>The value must be positive.
To specify that instances need no additional size (that is, size should be
inherited), omit the <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_extra_basicsize</span></code> slot rather than
set it to zero.</p>
<p>Specifying both <a class="reference internal" href="#c.Py_tp_basicsize" title="Py_tp_basicsize"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_basicsize</span></code></a> and
<code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_extra_basicsize</span></code> is an error.</p>
<p>This may not be used in <a class="reference internal" href="#c.PyType_Spec.slots" title="PyType_Spec.slots"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.slots</span></code></a>.
Use negative <a class="reference internal" href="#c.PyType_Spec.basicsize" title="PyType_Spec.basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.basicsize</span></code></a> instead.</p>
<p>This slot may not be used with <a class="reference internal" href="#c.PyType_GetSlot" title="PyType_GetSlot"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetSlot()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_tp_itemsize">
<span class="sig-name descname"><span class="n"><span class="pre">Py_tp_itemsize</span></span></span><a class="headerlink" href="#c.Py_tp_itemsize" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for the size of one element of a
variable-size type, in bytes.
Used to set <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyTypeObject.tp_itemsize</span></code></a>.
See <code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code> documentation for caveats.</p>
<p>The value must be positive.</p>
<p>If this slot is missing, <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a> is inherited.
Extending arbitrary variable-sized classes is dangerous,
since some types use a fixed offset for variable-sized memory,
which can then overlap fixed-sized memory used by a subclass.
To help prevent mistakes, inheriting <code class="docutils literal notranslate"><span class="pre">itemsize</span></code> is only possible
in the following situations:</p>
<ul class="simple">
<li><p>The base is not variable-sized (its
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a> is zero).</p></li>
<li><p>The requested <a class="reference internal" href="#c.PyType_Spec.basicsize" title="PyType_Spec.basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.basicsize</span></code></a> is positive,
suggesting that the memory layout of the base class is known.</p></li>
<li><p>The requested <a class="reference internal" href="#c.PyType_Spec.basicsize" title="PyType_Spec.basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.basicsize</span></code></a> is zero,
suggesting that the subclass does not access the instance’s memory
directly.</p></li>
<li><p>With the <a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_ITEMS_AT_END" title="Py_TPFLAGS_ITEMS_AT_END"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_ITEMS_AT_END</span></code></a> flag.</p></li>
</ul>
<p>This may not be used in <a class="reference internal" href="#c.PyType_Spec.slots" title="PyType_Spec.slots"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.slots</span></code></a>.
Use <a class="reference internal" href="#c.PyType_Spec.itemsize" title="PyType_Spec.itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.itemsize</span></code></a> instead.</p>
<p>This slot may not be used with <a class="reference internal" href="#c.PyType_GetSlot" title="PyType_GetSlot"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetSlot()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_tp_flags">
<span class="sig-name descname"><span class="n"><span class="pre">Py_tp_flags</span></span></span><a class="headerlink" href="#c.Py_tp_flags" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for type flags, used to set
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_flags" title="PyTypeObject.tp_flags"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyTypeObject.tp_flags</span></code></a>.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">Py_TPFLAGS_HEAPTYPE</span></code> flag is not set,
<a class="reference internal" href="#c.PyType_FromSpecWithBases" title="PyType_FromSpecWithBases"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromSpecWithBases()</span></code></a> sets it automatically.</p>
<p>This may not be used in <a class="reference internal" href="#c.PyType_Spec.slots" title="PyType_Spec.slots"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.slots</span></code></a>.
Use negative <a class="reference internal" href="#c.PyType_Spec.basicsize" title="PyType_Spec.basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.basicsize</span></code></a> instead.</p>
<p>This slot may not be used with <a class="reference internal" href="#c.PyType_GetSlot" title="PyType_GetSlot"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetSlot()</span></code></a>.
Use <a class="reference internal" href="#c.PyType_GetFlags" title="PyType_GetFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetFlags()</span></code></a> instead.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_tp_bases">
<span class="sig-name descname"><span class="n"><span class="pre">Py_tp_bases</span></span></span><a class="headerlink" href="#c.Py_tp_bases" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for type flags, used to set
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_bases" title="PyTypeObject.tp_bases"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyTypeObject.tp_bases</span></code></a>.</p>
<p>The slot can be set to a tuple of type objects which the newly created
type should inherit from, like the “positional arguments” of
a Python <a class="reference internal" href="../reference/compound_stmts.html#class"><span class="std std-ref">class definition</span></a>.</p>
<p>Alternately, the slot can be set to a single type object to specify
a single base.
The effect is the same as specifying a one-element tuple.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>Previously, <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_bases</span></code> required a tuple of types.</p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_tp_base">
<span class="sig-name descname"><span class="n"><span class="pre">Py_tp_base</span></span></span><a class="headerlink" href="#c.Py_tp_base" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Equivalent to <a class="reference internal" href="#c.Py_tp_bases" title="Py_tp_bases"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_bases</span></code></a> (with <code class="docutils literal notranslate"><span class="pre">s</span></code> at the end).
If both are specified, <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_bases</span></code> takes priority and
this slot is ignored.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>Previously, <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_base</span></code> required a single type, not a tuple.</p>
</div>
<div class="versionchanged soft-deprecated">
<p><span class="versionmodified soft-deprecated"><a class="reference internal" href="../glossary.html#term-soft-deprecated">Soft deprecated</a> since version 3.15: </span>When not targeting older Python versions, prefer <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_bases</span></code>.</p>
</div>
</dd></dl>
<p>The following slots do not correspond to public fields in the
underlying structures:</p>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_tp_metaclass">
<span class="sig-name descname"><span class="n"><span class="pre">Py_tp_metaclass</span></span></span><a class="headerlink" href="#c.Py_tp_metaclass" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for the metaclass used to construct
the resulting type object.
When omitted the metaclass is derived from bases
(<a class="reference internal" href="#c.Py_tp_bases" title="Py_tp_bases"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_bases</span></code></a> or the <em>bases</em> argument of
<a class="reference internal" href="#c.PyType_FromMetaclass" title="PyType_FromMetaclass"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromMetaclass()</span></code></a>).</p>
<p>Metaclasses that override <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> are not
supported, except if <code class="docutils literal notranslate"><span class="pre">tp_new</span></code> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<p>This may not be used in <a class="reference internal" href="#c.PyType_Spec.slots" title="PyType_Spec.slots"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.slots</span></code></a>.
Use <a class="reference internal" href="#c.PyType_FromMetaclass" title="PyType_FromMetaclass"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromMetaclass()</span></code></a> to specify a metaclass with
<code class="xref c c-type docutils literal notranslate"><span class="pre">PyType_Spec</span></code>.</p>
<p>This slot may not be used with <a class="reference internal" href="#c.PyType_GetSlot" title="PyType_GetSlot"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetSlot()</span></code></a>.
Use <a class="reference internal" href="structures.html#c.Py_TYPE" title="Py_TYPE"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_TYPE()</span></code></a> on the type object instead.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_tp_module">
<span class="sig-name descname"><span class="n"><span class="pre">Py_tp_module</span></span></span><a class="headerlink" href="#c.Py_tp_module" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for recording the module in which
the new class is defined.</p>
<p>The value must be a module object.
The module is associated with the new type and can later be
retrieved with <a class="reference internal" href="#c.PyType_GetModule" title="PyType_GetModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetModule()</span></code></a>.
The associated module is not inherited by subclasses; it must be specified
for each class individually.</p>
<p>This may not be used in <a class="reference internal" href="#c.PyType_Spec.slots" title="PyType_Spec.slots"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.slots</span></code></a>.
Use <a class="reference internal" href="#c.PyType_FromMetaclass" title="PyType_FromMetaclass"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromMetaclass()</span></code></a> to specify a module with
<code class="xref c c-type docutils literal notranslate"><span class="pre">PyType_Spec</span></code>.</p>
<p>This slot may not be used with <a class="reference internal" href="#c.PyType_GetSlot" title="PyType_GetSlot"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetSlot()</span></code></a>.
Use <a class="reference internal" href="#c.PyType_GetModule" title="PyType_GetModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetModule()</span></code></a> instead.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_tp_token">
<span class="sig-name descname"><span class="n"><span class="pre">Py_tp_token</span></span></span><a class="headerlink" href="#c.Py_tp_token" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.14.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> for recording a static memory layout ID
for a class.</p>
<p>If the class is defined using a <a class="reference internal" href="#c.PyType_Spec" title="PyType_Spec"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyType_Spec</span></code></a>, and that spec is
statically allocated, the token can be set to the spec using the special
value <a class="reference internal" href="#c.Py_TP_USE_SPEC" title="Py_TP_USE_SPEC"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_TP_USE_SPEC</span></code></a>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="n">PyType_Slot</span><span class="w"> </span><span class="n">foo_slots</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="p">{</span><span class="n">Py_tp_token</span><span class="p">,</span><span class="w"> </span><span class="n">Py_TP_USE_SPEC</span><span class="p">},</span>
</pre></div>
</div>
<p>It can also be set to an arbitrary pointer, but you must ensure that:</p>
<ul class="simple">
<li><p>The pointer outlives the class, so it’s not reused for something else
while the class exists.</p></li>
<li><p>It “belongs” to the extension module where the class lives, so it will not
clash with other extensions.</p></li>
</ul>
<p>Use <a class="reference internal" href="#c.PyType_GetBaseByToken" title="PyType_GetBaseByToken"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetBaseByToken()</span></code></a> to check if a class’s superclass has
a given token – that is, check whether the memory layout is compatible.</p>
<p>To get the token for a given class (without considering superclasses),
use <a class="reference internal" href="#c.PyType_GetSlot" title="PyType_GetSlot"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GetSlot()</span></code></a> with <code class="docutils literal notranslate"><span class="pre">Py_tp_token</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.14.</span></p>
</div>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_TP_USE_SPEC">
<span class="sig-name descname"><span class="n"><span class="pre">Py_TP_USE_SPEC</span></span></span><a class="headerlink" href="#c.Py_TP_USE_SPEC" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.14.</em><p>Used as a value with <a class="reference internal" href="#c.Py_tp_token" title="Py_tp_token"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_token</span></code></a> to set the token to the
class’s <a class="reference internal" href="#c.PyType_Spec" title="PyType_Spec"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyType_Spec</span></code></a>.
May only be used for classes defined using <code class="xref c c-type docutils literal notranslate"><span class="pre">PyType_Spec</span></code>.</p>
<p>Expands to <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.14.</span></p>
</div>
</dd></dl>
</dd></dl>
<dl class="c macro">
<dt class="sig sig-object c" id="c.Py_tp_slots">
<span class="sig-name descname"><span class="n"><span class="pre">Py_tp_slots</span></span></span><a class="headerlink" href="#c.Py_tp_slots" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p><a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">Slot</span> <span class="pre">ID</span></code></a> that works like
<a class="reference internal" href="slots.html#c.Py_slot_subslots" title="Py_slot_subslots"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_slot_subslots</span></code></a>, except it specifies an array of
<a class="reference internal" href="#c.PyType_Slot" title="PyType_Slot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyType_Slot</span></code></a> structures.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
</section>
</section>
<section id="soft-deprecated-api">
<h2>Soft-deprecated API<a class="headerlink" href="#soft-deprecated-api" title="Link to this heading">¶</a></h2>
<p>The following functions are <a class="reference internal" href="../glossary.html#term-soft-deprecated"><span class="xref std std-term">soft deprecated</span></a>.
They will continue to work, but new features will be added as slots for
<a class="reference internal" href="#c.PyType_FromSlots" title="PyType_FromSlots"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromSlots()</span></code></a>, not as arguments to new <code class="docutils literal notranslate"><span class="pre">PyType_From*</span></code> functions.</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_FromMetaclass">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_FromMetaclass</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">metaclass</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <a class="reference internal" href="#c.PyType_Spec" title="PyType_Spec"><span class="n"><span class="pre">PyType_Spec</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">spec</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">bases</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_FromMetaclass" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.12.</em><p>Create and return a <a class="reference internal" href="typeobj.html#heap-types"><span class="std std-ref">heap type</span></a> from the <em>spec</em>
(see <a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_HEAPTYPE" title="Py_TPFLAGS_HEAPTYPE"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_HEAPTYPE</span></code></a>).</p>
<p>A non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code> <em>metaclass</em> argument corresponds to the
<a class="reference internal" href="#c.Py_tp_metaclass" title="Py_tp_metaclass"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_metaclass</span></code></a> slot.</p>
<p>A non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code> <em>bases</em> argument corresponds to the <a class="reference internal" href="#c.Py_tp_bases" title="Py_tp_bases"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_bases</span></code></a>
slot, and takes precedence over <code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_bases</span></code> and
<code class="xref c c-data docutils literal notranslate"><span class="pre">Py_tp_bases</span></code> slots.</p>
<p>A non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code> <em>module</em> argument corresponds to the
<a class="reference internal" href="#c.Py_tp_module" title="Py_tp_module"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_module</span></code></a> slot.</p>
<p>This function calls <a class="reference internal" href="#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready()</span></code></a> on the new type.</p>
<p>Note that this function does <em>not</em> fully match the behavior of
calling <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type()</span></code></a> or using the <a class="reference internal" href="../reference/compound_stmts.html#class"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">class</span></code></a> statement.
See the note in <a class="reference internal" href="#c.PyType_FromSlots" title="PyType_FromSlots"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromSlots()</span></code></a> documentation for details.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.12.</span></p>
</div>
<div class="versionchanged soft-deprecated">
<p><span class="versionmodified soft-deprecated"><a class="reference internal" href="../glossary.html#term-soft-deprecated">Soft deprecated</a> since version 3.15.0rc1 (unreleased): </span>Prefer <a class="reference internal" href="#c.PyType_FromSlots" title="PyType_FromSlots"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromSlots()</span></code></a> in new code.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_FromModuleAndSpec">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_FromModuleAndSpec</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">module</span></span>, <a class="reference internal" href="#c.PyType_Spec" title="PyType_Spec"><span class="n"><span class="pre">PyType_Spec</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">spec</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">bases</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_FromModuleAndSpec" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">PyType_FromMetaclass(NULL,</span> <span class="pre">module,</span> <span class="pre">spec,</span> <span class="pre">bases)</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.9.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.10: </span>The function now accepts a single class as the <em>bases</em> argument and
<code class="docutils literal notranslate"><span class="pre">NULL</span></code> as the <code class="docutils literal notranslate"><span class="pre">tp_doc</span></code> slot.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.12: </span>The function now finds and uses a metaclass corresponding to the provided
base classes. Previously, only <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type</span></code></a> instances were returned.</p>
<p>The <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> of the metaclass is <em>ignored</em>.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
<code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code> is deprecated.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.14: </span>Creating classes whose metaclass overrides
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> is no longer allowed.</p>
</div>
<div class="versionchanged soft-deprecated">
<p><span class="versionmodified soft-deprecated"><a class="reference internal" href="../glossary.html#term-soft-deprecated">Soft deprecated</a> since version 3.15.0rc1 (unreleased): </span>Prefer <a class="reference internal" href="#c.PyType_FromSlots" title="PyType_FromSlots"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromSlots()</span></code></a> in new code.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_FromSpecWithBases">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_FromSpecWithBases</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyType_Spec" title="PyType_Spec"><span class="n"><span class="pre">PyType_Spec</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">spec</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">bases</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_FromSpecWithBases" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.3.</em><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">PyType_FromMetaclass(NULL,</span> <span class="pre">NULL,</span> <span class="pre">spec,</span> <span class="pre">bases)</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.3.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.12: </span>The function now finds and uses a metaclass corresponding to the provided
base classes. Previously, only <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type</span></code></a> instances were returned.</p>
<p>The <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> of the metaclass is <em>ignored</em>.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
<code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code> is deprecated.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.14: </span>Creating classes whose metaclass overrides
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> is no longer allowed.</p>
</div>
<div class="versionchanged soft-deprecated">
<p><span class="versionmodified soft-deprecated"><a class="reference internal" href="../glossary.html#term-soft-deprecated">Soft deprecated</a> since version 3.15.0rc1 (unreleased): </span>Prefer <a class="reference internal" href="#c.PyType_FromSlots" title="PyType_FromSlots"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromSlots()</span></code></a> in new code.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyType_FromSpec">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyType_FromSpec</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyType_Spec" title="PyType_Spec"><span class="n"><span class="pre">PyType_Spec</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">spec</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_FromSpec" title="Link to this definition">¶</a><br /></dt>
<dd><em class="refcount return_new_ref">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">PyType_FromMetaclass(NULL,</span> <span class="pre">NULL,</span> <span class="pre">spec,</span> <span class="pre">NULL)</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.12: </span>The function now finds and uses a metaclass corresponding to the
base classes provided in <em>Py_tp_base[s]</em> slots.
Previously, only <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type</span></code></a> instances were returned.</p>
<p>The <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> of the metaclass is <em>ignored</em>.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
<code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code> is deprecated.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.14: </span>Creating classes whose metaclass overrides
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> is no longer allowed.</p>
</div>
<div class="versionchanged soft-deprecated">
<p><span class="versionmodified soft-deprecated"><a class="reference internal" href="../glossary.html#term-soft-deprecated">Soft deprecated</a> since version 3.15.0rc1 (unreleased): </span>Prefer <a class="reference internal" href="#c.PyType_FromSlots" title="PyType_FromSlots"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromSlots()</span></code></a> in new code.</p>
</div>
</dd></dl>
<!-- Keep old URL fragments working (see gh-97908) -->
<span id='c.PyType_Spec.PyType_Spec.name'></span>
<span id='c.PyType_Spec.PyType_Spec.basicsize'></span>
<span id='c.PyType_Spec.PyType_Spec.itemsize'></span>
<span id='c.PyType_Spec.PyType_Spec.flags'></span>
<span id='c.PyType_Spec.PyType_Spec.slots'></span><dl class="c type">
<dt class="sig sig-object c" id="c.PyType_Spec">
<span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_Spec</span></span></span><a class="headerlink" href="#c.PyType_Spec" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> (including all members).</em><p>Structure defining a type’s behavior, used for soft-deprecated functions
like <a class="reference internal" href="#c.PyType_FromMetaclass" title="PyType_FromMetaclass"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromMetaclass()</span></code></a>.</p>
<p>This structure contains several members that can instead be specified
as <a class="reference internal" href="#pyslot-type-slot-ids"><span class="std std-ref">slots</span></a> for <a class="reference internal" href="#c.PyType_FromSlots" title="PyType_FromSlots"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromSlots()</span></code></a>,
and an array of slot entries with a simpler structure.</p>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyType_Spec.name">
<span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">name</span></span></span><a class="headerlink" href="#c.PyType_Spec.name" title="Link to this definition">¶</a><br /></dt>
<dd><p>Corresponds to <a class="reference internal" href="#c.Py_tp_name" title="Py_tp_name"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_name</span></code></a>.</p>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyType_Spec.basicsize">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">basicsize</span></span></span><a class="headerlink" href="#c.PyType_Spec.basicsize" title="Link to this definition">¶</a><br /></dt>
<dd><p>If positive, corresponds to <a class="reference internal" href="#c.Py_tp_basicsize" title="Py_tp_basicsize"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_basicsize</span></code></a>.</p>
<p>If negative, corresponds to <a class="reference internal" href="#c.Py_tp_extra_basicsize" title="Py_tp_extra_basicsize"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_extra_basicsize</span></code></a> set to
the absolute value.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.12: </span>Previously, this field could not be negative.</p>
</div>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyType_Spec.itemsize">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">itemsize</span></span></span><a class="headerlink" href="#c.PyType_Spec.itemsize" title="Link to this definition">¶</a><br /></dt>
<dd><p>Corresponds to <a class="reference internal" href="#c.Py_tp_itemsize" title="Py_tp_itemsize"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_itemsize</span></code></a>.</p>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyType_Spec.flags">
<span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">flags</span></span></span><a class="headerlink" href="#c.PyType_Spec.flags" title="Link to this definition">¶</a><br /></dt>
<dd><p>Corresponds to <a class="reference internal" href="#c.Py_tp_flags" title="Py_tp_flags"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_flags</span></code></a>.</p>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyType_Spec.slots">
<a class="reference internal" href="#c.PyType_Slot" title="PyType_Slot"><span class="n"><span class="pre">PyType_Slot</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">slots</span></span></span><a class="headerlink" href="#c.PyType_Spec.slots" title="Link to this definition">¶</a><br /></dt>
<dd><p>Array of <a class="reference internal" href="#c.PyType_Slot" title="PyType_Slot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyType_Slot</span></code></a> (not <a class="reference internal" href="slots.html#c.PySlot" title="PySlot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySlot</span></code></a>) structures.</p>
<p>Terminated by the special slot value <code class="docutils literal notranslate"><span class="pre">{0,</span> <span class="pre">NULL}</span></code>.
Each slot ID should be specified at most once.</p>
<!-- Keep old URL fragments working (see gh-97908) -->
<span id='c.PyType_Slot.PyType_Slot.slot'></span>
<span id='c.PyType_Slot.PyType_Slot.pfunc'></span><dl class="c type">
<dt class="sig sig-object c" id="c.PyType_Slot">
<span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_Slot</span></span></span><a class="headerlink" href="#c.PyType_Slot" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> (including all members).</em><p>Structure defining optional functionality of a type, used for
soft-deprecated functions like <a class="reference internal" href="#c.PyType_FromMetaclass" title="PyType_FromMetaclass"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_FromMetaclass()</span></code></a>.</p>
<p>Note that a <code class="xref c c-type docutils literal notranslate"><span class="pre">PyType_Slot</span></code> array may be included in a
<code class="xref c c-type docutils literal notranslate"><span class="pre">PySlot</span></code> array using <a class="reference internal" href="#c.Py_tp_slots" title="Py_tp_slots"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_slots</span></code></a>,
and vice versa using <a class="reference internal" href="slots.html#c.Py_slot_subslots" title="Py_slot_subslots"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_slot_subslots</span></code></a>.</p>
<p>Each <code class="xref c c-type docutils literal notranslate"><span class="pre">PyType_Slot</span></code> structure <code class="docutils literal notranslate"><span class="pre">tpslot</span></code> is interpreted
as the following <a class="reference internal" href="slots.html#c.PySlot" title="PySlot"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySlot</span></code></a> structure:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">PySlot</span><span class="p">){</span>
<span class="w"> </span><span class="p">.</span><span class="n">sl_id</span><span class="o">=</span><span class="n">tpslot</span><span class="p">.</span><span class="n">slot</span><span class="p">,</span>
<span class="w"> </span><span class="p">.</span><span class="n">sl_flags</span><span class="o">=</span><span class="n">PySlot_INTPTR</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">sub_static</span><span class="p">,</span>
<span class="w"> </span><span class="p">.</span><span class="n">sl_ptr</span><span class="o">=</span><span class="n">tpslot</span><span class="p">.</span><span class="n">func</span>
<span class="p">}</span>
</pre></div>
</div>
<p>where <code class="docutils literal notranslate"><span class="pre">sub_static</span></code> is <code class="docutils literal notranslate"><span class="pre">PySlot_STATIC</span></code> if the slot requires
the flag (such as for <a class="reference internal" href="typeobj.html#c.Py_tp_methods" title="Py_tp_methods"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_methods</span></code></a>), or if this flag
is present on the “parent” <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_tp_slots</span></code> slot (if any).</p>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyType_Slot.slot">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">slot</span></span></span><a class="headerlink" href="#c.PyType_Slot.slot" title="Link to this definition">¶</a><br /></dt>
<dd><p>Corresponds to <a class="reference internal" href="slots.html#c.PySlot.sl_id" title="PySlot.sl_id"><code class="xref c c-member docutils literal notranslate"><span class="pre">PySlot.sl_id</span></code></a>.</p>
</dd></dl>
<dl class="c member">
<dt class="sig sig-object c" id="c.PyType_Slot.pfunc">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">pfunc</span></span></span><a class="headerlink" href="#c.PyType_Slot.pfunc" title="Link to this definition">¶</a><br /></dt>
<dd><p>Corresponds to <a class="reference internal" href="slots.html#c.PySlot.sl_ptr" title="PySlot.sl_ptr"><code class="xref c c-member docutils literal notranslate"><span class="pre">PySlot.sl_ptr</span></code></a>.</p>
</dd></dl>
</dd></dl>
</dd></dl>
</dd></dl>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Type Objects</a><ul>
<li><a class="reference internal" href="#creating-heap-allocated-types">Creating Heap-Allocated Types</a><ul>
<li><a class="reference internal" href="#type-slot-ids">Type slot IDs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#soft-deprecated-api">Soft-deprecated API</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="concrete.html"
title="previous chapter">Concrete Objects Layer</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="none.html"
title="next chapter">The <code class="docutils literal notranslate"><span class="pre">None</span></code> Object</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "c-api/type.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/c-api/type.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="none.html" title="The None Object"
>next</a> |</li>
<li class="right" >
<a href="concrete.html" title="Concrete Objects Layer"
>previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0rc1 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API reference manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
<li class="nav-item nav-item-this"><a href="">Type Objects</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
<br>
This page is licensed under the Python Software Foundation License Version 2.
<br>
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br>
See <a href="/license.html">History and License</a> for more information.<br>
<br>
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
<br>
Last updated on Aug 04, 2026 (11:13 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>